home *** CD-ROM | disk | FTP | other *** search
/ CD Actual 22 / PC Actual CD 22.iso / linux / xfree86 / DOC / README.fbdev < prev    next >
Encoding:
Text File  |  1998-01-07  |  16.4 KB  |  727 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.               The Linux/m68k Frame Buffer Device
  11.  
  12.        Geert Uytterhoeven (Geert.Uytterhoeven@cs.kuleuven.ac.be)
  13.  
  14.                   14 May 1997
  15.  
  16.  
  17.  
  18. 1.  Introduction
  19.  
  20. The frame buffer device provides an abstraction for the graphics hardware. It
  21. represents the frame buffer of some video hardware and allows application soft-
  22. ware to access the graphics hardware through a well-defined interface, so the
  23. software doesn't need to know anything about the low-level (hardware register)
  24. stuff.
  25.  
  26. The device is accessed through special device nodes, usually located in the
  27. /dev directory, i.e. /dev/fb*.
  28.  
  29.  
  30. 2.  User's View of /dev/fb*
  31.  
  32. From the user's point of view, the frame buffer device looks just like any
  33. other device in /dev. It's a character device using major 29, the minor is
  34. divided into a frame buffer number in the upper 3 bits (allowing max.  8 frame
  35. buffers simultaneously) and a resolution code in the lower 5 bits of the minor.
  36.  
  37. By convention, the following device nodes are used (numbers indicate the device
  38. minor numbers):
  39.  
  40.    o First frame buffer
  41.  
  42.        0 = /dev/fb0current
  43.          Current resolution
  44.  
  45.        1 = /dev/fb0autodetect
  46.          Default resolution
  47.  
  48.        2 = /dev/fb0predefined0
  49.          Predefined resolution 1
  50.  
  51.        ...
  52.  
  53.        23 = /dev/fb0predefined21
  54.          Predefined resolution 22
  55.  
  56.        24 = /dev/fb0user0
  57.          User defined resolutions 1
  58.  
  59.        ...
  60.  
  61.  
  62.  
  63.  
  64. The Linux/m68k Frame Buffer Device
  65.  
  66.  
  67.  
  68.  
  69.  
  70. The Linux/m68k Frame Buffer Device
  71.  
  72.  
  73.  
  74.        31 = /dev/fb0user7
  75.          User defined resolutions 8
  76.  
  77.  
  78.    o Second frame buffer
  79.  
  80.        32 = /dev/fb1current
  81.          Current resolution
  82.  
  83.        33 = /dev/fb1autodetect
  84.          Default resolution
  85.  
  86.        34 = /dev/fb1predefined0
  87.          Predefined resolutions 1
  88.  
  89.        ...
  90.  
  91.        55 = /dev/fb1predefined21
  92.          Predefined resolution 22
  93.  
  94.        56 = /dev/fb1user0
  95.          User defined resolutions 1
  96.  
  97.        ...
  98.  
  99.        63 = /dev/fb1user7
  100.          User defined resolutions 8
  101.  
  102. and so on...
  103.  
  104. The device with (minor & 31) == 0 (/dev/fb?current) stands for the frame buffer
  105. together with the currently set video parameters; (minor & 31) == 1
  106. (/dev/fb?autodetect) is the video mode detected at boot time. Any other minor
  107. stands for some predefined or user defined video mode.
  108.  
  109. The predefined entries (/dev/fb?predefined*) usually have a device dependent
  110. name, e.g. for major 29, minor 5, we have /dev/fb0multiscan on Amiga and
  111. /dev/fb0ttmid on Atari. These are meant to contain hardware dependent resolu-
  112. tions.
  113.  
  114. The user defined resolutions (/dev/fb?user?) are meant to be filled in by the
  115. user. This way the user can store his favorite 8 resolutions during boot up.
  116.  
  117. Note: if you need more than 8 user defined resolutions, you can always override
  118. the predefined resolutions by storing them in one of the predefined entries.
  119. But this is not recommended. Similarly, if there are more than 22 predefined
  120. resolutions, the device writer can decide to store them in the user defined
  121. entries.
  122.  
  123. If the device is opened (for writing), the frame buffer driver switches to the
  124. selected video mode. Thus, you can switch video modes by writing to a frame
  125. buffer device, e.g.
  126.  
  127.  
  128.  
  129.  
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. The Linux/m68k Frame Buffer Device
  137.  
  138.  
  139.  
  140.      > /dev/fb0ttlow
  141.  
  142.  
  143. will switch your video to TT low mode. Note: if you specify a resolution which
  144. contains a value that's not possible on your hardware, the frame buffer device
  145. will round it up (if possible) or return an error condition.
  146.  
  147. The frame buffer devices are also `normal' memory devices, this means, you can
  148. read and write their contents. You can, for example, make a screen snapshot by
  149.  
  150.      cp /dev/fb0current myfile
  151.  
  152.  
  153. There also can be more than one frame buffer at a time, e.g. if you have a
  154. graphics card in addition to the built-in hardware. The corresponding frame
  155. buffer devices (/dev/fb0* and /dev/fb1* etc.) work independently.
  156.  
  157. Application software that uses the frame buffer device (e.g. the X server) will
  158. use /dev/fb0current by default. You can specify an alternative resolution by
  159. setting the environment variable $FRAMEBUFFER to the path name of a frame
  160. buffer device, e.g. (for sh/bash users):
  161.  
  162.      export FRAMEBUFFER=/dev/fb0multiscan
  163.  
  164.  
  165. or (for csh users):
  166.  
  167.      setenv FRAMEBUFFER /dev/fb0multiscan
  168.  
  169.  
  170. After this the X server will use the multiscan video mode.
  171.  
  172.  
  173. 3.  Programmer's View of /dev/fb*
  174.  
  175. As you already know, a frame buffer device is a memory device like /dev/mem and
  176. it has the same features. You can read it, write it, seek to some location in
  177. it and mmap() it (the main usage). The difference is just that the memory that
  178. appears in the special file is not the whole memory, but the frame buffer of
  179. some video hardware.
  180.  
  181. /dev/fb* also allows several ioctls on it, by which lots of information about
  182. the hardware can be queried and set. The color map handling works via ioctls,
  183. too. Look into <linux/fb.h> for more information on what ioctls exist and on
  184. which data structures they work. Here's just a brief overview:
  185.  
  186.    o You can request unchangeable information about the hardware, like name,
  187.      organization of the screen memory (planes, packed pixels, ...) and address
  188.      and length of the screen memory.
  189.  
  190.    o You can request and change variable information about the hardware, like
  191.      visible and virtual geometry, depth, color map format, timing, and so on.
  192.      If you try to change that informations, the driver maybe will round up
  193.      some values to meet the hardware's capabilities (or return EINVAL if that
  194.  
  195.  
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. The Linux/m68k Frame Buffer Device
  203.  
  204.  
  205.  
  206.      isn't possible).
  207.  
  208.    o You can get and set parts of the color map. Communication is done with 16
  209.      bit per color part (red, green, blue, transparency) to support all exist-
  210.      ing hardware. The driver does all the computations needed to bring it into
  211.      the hardware (round it down to less bits, maybe throw away transparency).
  212.  
  213. All this hardware abstraction makes the implementation of application programs
  214. easier and more portable. E.g. the X server works completely on /dev/fb* and
  215. thus doesn't need to know, for example, how the color registers of the concrete
  216. hardware are organized. XF68_FBDev is a general X server for bitmapped, unac-
  217. celerated video hardware. The only thing that has to be built into application
  218. programs is the screen organization (bitplanes or chunky pixels etc.), because
  219. it works on the frame buffer image data directly.
  220.  
  221. For the future it is planned that frame buffer drivers for graphics cards and
  222. the like can be implemented as kernel modules that are loaded at runtime. Such
  223. a driver just has to call register_framebuffer() and supply some functions.
  224. Writing and distributing such drivers independently from the kernel will save
  225. much trouble...
  226.  
  227.  
  228. 4.  Frame Buffer Resolution Maintenance
  229.  
  230. Frame buffer resolutions are maintained using the utility fbset. It allows to
  231. change the video mode properties of the current or a user defined resolution.
  232. It's main usage is to tune video modes and to store custom resolutions into one
  233. of the /dev/fb?user?  entries, e.g. during boot up in one of your /etc/rc.* or
  234. /etc/init.d/* files, after which those resolutions can be used by applications.
  235.  
  236. Fbset uses a video mode database stored in a configuration file, so you can
  237. easily add your own modes and refer to them with a simple identifier. The fbset
  238. install script also creates the special device nodes for the device dependent
  239. predefined resolutions.
  240.  
  241.  
  242. 5.  The X Server
  243.  
  244. The X server (XF68_FBDev) is the most notable application program for the frame
  245. buffer device. Starting with XFree68/XFree86 release 3.2, the X server is part
  246. of XFree68/XFree86 and has 2 modes:
  247.  
  248.    o If the Display subsection for the fbdev driver in the /etc/XF86Config file
  249.      contains a
  250.  
  251.  
  252.           Modes "default"
  253.  
  254.  
  255.  
  256.  
  257.      line, the X server will use the scheme discussed above, i.e. it will start
  258.      up in the resolution determined by /dev/fb0current (or $FRAMEBUFFER, if
  259.      set). This is the default for the configuration file supplied with
  260.  
  261.  
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268. The Linux/m68k Frame Buffer Device
  269.  
  270.  
  271.  
  272.      XFree68. It's the most simple configuration (and the only possible one if
  273.      you want to have a broadcast compatible display, e.g.  PAL or NTSC), but
  274.      it has some limitations.
  275.  
  276.    o Therefore it's also possible to specify resolutions in the /etc/XF86Config
  277.      file. This allows for on-the-fly resolution switching while retaining the
  278.      same virtual desktop size. The frame buffer device that's used is still
  279.      /dev/fb0current (or $FRAMEBUFFER), but the available resolutions are
  280.      defined by /etc/XF86Config now. The disadvantage is that you have to spec-
  281.      ify the timings in a different format (but fbset -x may help) and that you
  282.      can't have a broadcast compatible display (e.g. no PAL or NTSC).
  283.  
  284. To tune a video mode, you can use fbset or xvidtune. Note that xvidtune doesn't
  285. work 100% with XF68_FBDev: the reported clock values are always incorrect.
  286.  
  287. There exists also an accelerated X server for the Cybervision 64 graphics
  288. board, but that's not discussed here.
  289.  
  290.  
  291. 6.  Video Mode Timings
  292.  
  293. A monitor draws an image on the screen by using an electron beam (3 electron
  294. beams for most color models, 1 electron beam for Trinitron color monitors and
  295. monochrome monitors). The front of the screen is covered by a pattern of col-
  296. ored phosphors (pixels). If a phosphor is hit by an electron, it emits a photon
  297. and thus becomes visible.
  298.  
  299. The electron beam draws horizontal lines (scanlines) from left to right, and
  300. from the top to the bottom of the screen. By modifying the intensity of the
  301. electron beam, pixels with various colors and intensities can be shown.
  302.  
  303. After each scanline the electron beam has to move back to the left side of the
  304. screen and to the next line: this is called the horizontal retrace. After the
  305. whole screen (frame) was painted, the beam moves back to the upper left corner:
  306. this is called the vertical retrace. During both the horizontal and vertical
  307. retrace, the electron beam is turned off (blanked).
  308.  
  309. The speed at which the electron beam paints the pixels is determined by the
  310. dotclock in the graphics board. For a dotclock of e.g. 28.37516 MHz (millions
  311. of cycles per second), each pixel is 35242 ps (picoseconds) long:
  312.  
  313.  
  314.  
  315.  
  316. 1/(28.37516E6 Hz) = 35.242E-9 s
  317.  
  318. If the screen resolution is 640x480, it will take
  319.  
  320.      640*35.242E-9 s = 22.555E-6 s
  321.  
  322.  
  323. to paint the 640 (xres) pixels on one scanline. But the horizontal retrace also
  324. takes time (e.g. 272 `pixels'), so a full scanline takes
  325.  
  326.  
  327.  
  328.  
  329.  
  330.  
  331.  
  332.  
  333.  
  334. The Linux/m68k Frame Buffer Device
  335.  
  336.  
  337.  
  338.      (640+272)*35.242E-9 s = 32.141E-6 s
  339.  
  340.  
  341. We'll say that the horizontal scanrate is about 31 kHz:
  342.  
  343.      1/(32.141E-6 s) = 31.113E3 Hz
  344.  
  345.  
  346. A full screen counts 480 (yres) lines, but we have to consider the vertical
  347. retrace too (e.g. 49 `pixels'). So a full screen will take
  348.  
  349.      (480+49)*32.141E-6 s = 17.002E-3 s
  350.  
  351.  
  352. The vertical scanrate is about 59 Hz:
  353.  
  354.      1/(17.002E-3 s) = 58.815 Hz
  355.  
  356.  
  357. This means the screen data is refreshed about 59 times per second. To have a
  358. stable picture without visible flicker, VESA recommends a vertical scanrate of
  359. at least 72 Hz. But the perceived flicker is very human dependent: some people
  360. can use 50 Hz without any trouble, while I'll notice if it's less than 80 Hz.
  361.  
  362. Since the monitor doesn't know when a new scanline starts, the graphics board
  363. will supply a synchronization pulse (horizontal sync or hsync) for each scan-
  364. line.  Similarly it supplies a synchronization pulse (vertical sync or vsync)
  365. for each new frame. The position of the image on the screen is influenced by
  366. the moments at which the synchronization pulses occur.
  367.  
  368. The following picture summarizes all timings. The horizontal retrace time is
  369. the sum of the left margin, the right margin and the hsync length, while the
  370. vertical retrace time is the sum of the upper margin, the lower margin and the
  371. vsync length.
  372.  
  373.  
  374.  
  375.  
  376.  
  377.  
  378.  
  379.  
  380.  
  381.  
  382.  
  383.  
  384.  
  385.  
  386.  
  387.  
  388.  
  389.  
  390.  
  391.  
  392.  
  393.  
  394.  
  395.  
  396.  
  397.  
  398.  
  399.  
  400. The Linux/m68k Frame Buffer Device
  401.  
  402.  
  403.  
  404.        +----------+---------------------------------------------+----------+-------+
  405.        |      |           x                |       |       |
  406.        |      |           |upper_margin        |       |       |
  407.        |      |           x                |       |       |
  408.        +----------###############################################----------+-------+
  409.        |      #           x                #       |       |
  410.        |      #           |                #       |       |
  411.        |      #           |                #       |       |
  412.        |      #           |                #       |       |
  413.        |   left   #           |                #  right   | hsync |
  414.        |  margin  #           |       xres         #  margin  |  len  |
  415.        |<-------->#<---------------+--------------------------->#<-------->|<----->|
  416.        |      #           |                #       |       |
  417.        |      #           |                #       |       |
  418.        |      #           |                #       |       |
  419.        |      #           |yres            #       |       |
  420.        |      #           |                #       |       |
  421.        |      #           |                #       |       |
  422.        |      #           |                #       |       |
  423.        |      #           |                #       |       |
  424.        |      #           |                #       |       |
  425.        |      #           |                #       |       |
  426.        |      #           |                #       |       |
  427.        |      #           |                #       |       |
  428.        |      #           x                #       |       |
  429.        +----------###############################################----------+-------+
  430.        |      |           x                |       |       |
  431.        |      |           |lower_margin        |       |       |
  432.        |      |           x                |       |       |
  433.        +----------+---------------------------------------------+----------+-------+
  434.        |      |           x                |       |       |
  435.        |      |           |vsync_len            |       |       |
  436.        |      |           x                |       |       |
  437.        +----------+---------------------------------------------+----------+-------+
  438.  
  439. The frame buffer device expects all horizontal timings in number of dotclocks
  440. (in picoseconds, 1E-12 s), and vertical timings in number of scanlines.
  441.  
  442.  
  443. 7.  Converting XFree86 timing values into frame buffer device timings
  444.  
  445. An XFree86 mode line consists of the following fields:
  446.  
  447.      "800x600"     50      800  856  976 1040    600  637  643  666
  448.      < name >     DCF    HR  SH1  SH2  HFL     VR  SV1  SV2  VFL
  449.  
  450.  
  451. The frame buffer device uses the following fields:
  452.  
  453.       pixclock
  454.         pixel clock in ps (pico seconds)
  455.  
  456.       left_margin
  457.         time from sync to picture
  458.  
  459.  
  460.  
  461.  
  462.  
  463.  
  464.  
  465.  
  466. The Linux/m68k Frame Buffer Device
  467.  
  468.  
  469.  
  470.       right_margin
  471.         time from picture to sync
  472.  
  473.       upper_margin
  474.         time from sync to picture
  475.  
  476.       lower_margin
  477.         time from picture to sync
  478.  
  479.       hsync_len
  480.         length of horizontal sync
  481.  
  482.       vsync_len
  483.         length of vertical sync
  484.  
  485.       Pixelclock
  486.  
  487.            o xfree: in MHz
  488.  
  489.            o fb: In Picoseconds (ps)
  490.  
  491.            o pixclock = 1000000 / DCF
  492.  
  493.       Horizontal timings
  494.  
  495.            o left_margin = HFL - SH2
  496.  
  497.            o right_margin = SH1 - HR
  498.  
  499.            o hsync_len = SH2 - SH1
  500.  
  501.       Vertical timings
  502.  
  503.            o upper_margin = VFL - SV2
  504.  
  505.            o lower_margin = SV1 - VR
  506.  
  507.            o vsync_len = SV2 - SV1
  508.  
  509. Good examples for VESA timings can be found in the XFree86 source tree, under
  510. xc/programs/Xserver/hw/xfree86/doc/modeDB.txt.
  511.  
  512.  
  513. 8.  References
  514.  
  515. For more specific information about the frame buffer device and its applica-
  516. tions, please refer to the following documentation:
  517.  
  518.    o The manual pages for fbset: fbset(8), fb.modes(5)
  519.  
  520.    o The manual pages for XFree68: XF68_FBDev(1), XF86Config(4/5)
  521.  
  522.    o The mighty kernel sources:
  523.  
  524.  
  525.  
  526.  
  527.  
  528.  
  529.  
  530.  
  531.  
  532. The Linux/m68k Frame Buffer Device
  533.  
  534.  
  535.  
  536.     o linux/Documentation/m68k/framebuffer.txt, which may be more up-to-
  537.       date than the document you're reading now
  538.  
  539.     o linux/include/linux/fb.h
  540.  
  541.     o linux/drivers/char/fbmem.c
  542.  
  543.     o linux/arch/m68k/*/*fb.c
  544.  
  545.  
  546. 9.  Downloading
  547.  
  548. All necessary files can be found at
  549.  
  550.      ftp://ftp.uni-erlangen.de/pub/Linux/LOCAL/680x0/
  551.  
  552.  
  553. and on its mirrors.
  554.  
  555.  
  556. 10.  Credits
  557.  
  558.  
  559. This readme was written by Geert Uytterhoeven, partly based on the original X-
  560. framebuffer.README by Roman Hodek and Martin Schaller. Section `Converting
  561. XFree86 timing values into frame buffer device timings' was provided by Frank
  562. Neumann.
  563.  
  564. The frame buffer device abstraction was designed by Martin Schaller.
  565.  
  566.      Generated from XFree86: xc/programs/Xserver/hw/xfree68/doc/sgml/fbdev.sgml,v 1.1.2.5 1997/08/08 03:09:07 dawes Exp $
  567.  
  568.  
  569.  
  570.  
  571.  
  572.  
  573.  
  574.  
  575.  
  576.  
  577.  
  578.  
  579.  
  580.  
  581.  
  582.  
  583.  
  584.  
  585.  
  586.  
  587.  
  588.  
  589.  
  590.  
  591.  
  592.  
  593.  
  594.  
  595.  
  596.  
  597.  
  598. The Linux/m68k Frame Buffer Device
  599.  
  600.  
  601.  
  602.  
  603.  
  604.  
  605.  
  606.  
  607.  
  608.  
  609.  
  610.  
  611.  
  612.  
  613.  
  614.  
  615.  
  616.  
  617.  
  618.  
  619.  
  620.  
  621.  
  622.  
  623.  
  624.  
  625.  
  626.  
  627.  
  628.  
  629.  
  630.  
  631.  
  632.  
  633.  
  634.  
  635.  
  636.  
  637.  
  638.  
  639.  
  640.  
  641.  
  642.  
  643.  
  644.  
  645.  
  646.  
  647.  
  648.  
  649.  
  650.  
  651.  
  652.  
  653.  
  654.  
  655.  
  656.  
  657.  
  658.  
  659.  
  660.  
  661.  
  662.  
  663.  
  664.  
  665.  
  666.  
  667.  
  668.                    CONTENTS
  669.  
  670.  
  671.  
  672. 1.  Introduction ............................................................ 1
  673.  
  674. 2.  User's View of /dev/fb* ................................................. 1
  675.  
  676. 3.  Programmer's View of /dev/fb* ........................................... 3
  677.  
  678. 4.  Frame Buffer Resolution Maintenance ..................................... 4
  679.  
  680. 5.  The X Server ............................................................ 4
  681.  
  682. 6.  Video Mode Timings ...................................................... 5
  683.  
  684. 7.  Converting XFree86 timing values into frame buffer device timings ....... 7
  685.  
  686. 8.  References .............................................................. 8
  687.  
  688. 9.  Downloading ............................................................. 9
  689.  
  690. 10. Credits  ................................................................ 9
  691.  
  692.  
  693.  
  694.  
  695.  
  696.  
  697.  
  698.  
  699.  
  700.  
  701.  
  702.  
  703.  
  704.  
  705.  
  706.  
  707.  
  708.  
  709.  
  710.  
  711.  
  712.  
  713.  
  714.  
  715.  
  716.  
  717.  
  718.  
  719.  
  720.  
  721.  
  722.  
  723.  
  724.                        i
  725.  
  726.  
  727.